Axis properties






Xlim

 plt(...,'Xlim',[xmin xmax]);
Specifies the x-axis limits. If you are using a 2 column subplot, you can specify the x-limits for both columns by using a cell array. i.e. 'Xlim',{[xminL xmaxL]; [xminR xmaxR]}; If you want to specify just the right column limits, replace the left column limits with the string 'default'.

Ylim

 plt(...,'Ylim',[ymin ymax]);
Specifies the y-axis limits for the left-hand y axis of the main plot. Alternatively you may specify the limits for both the left and right-hand y-axes of the main plot using a cell array as in: 'Ylim',{[ymin ymax] [yminR ymaxR]}. The 'Right' parameter should also be included in this case, however if you don't, plt will default to placing the last trace on the right-hand axis. Note that this parameter only specifies limits for the main plot and never for any of the other subplots. If you need to set the y-axis limits for the other subplots, use the set command with the axis handles obtained from getappdata(gcf,'axis').

YlimR

 plt(...,'YlimR',[ymin ymax]);
Usually the y-axis limits are specified using the Ylim parameter (above) however if you only need to specify the limits for right-hand y axis use the YlimR parameter. The 'Right' parameter should also be included, however if you don't, plt will default to placing the last trace on the right-hand axis.

xy

 plt(...,'xy',p]);
 where p specifies new xy position/size coordinates for various graphical objects created by plt.
p is a 5 column matrix in the following format:
OID1 x y w h
OID2 x y w h
...        
OIDn x y w h

OID1 thru OIDn (Object IDs) are integers that specify the objects (often an axis) to be resized and repositioned. x and y represent the coordinates of the lower left edge of the object and w and h specify the width and height. (x,y,w,h may be in pixels or normalized units i.e. as a fraction of the window size).
The OIDs are described in the following table:

OID  
1 The main (left) plot axis
2 This usually represents the right-hand axis. However, if subplots have been specified This represents the first subplot. The remaining subplots are numbered sequentially and then the next number after the last subplot is assigned to the right-hand axis. (Note that this means that the OID for an axis will be it's index into the getappdata(gcf,'axis') array since it is ordered the same way.)
0 This is the only OID that refers to more than one object, i.e. both the main left and right-hand axes. If there is no right-hand axis, OIDs 0 and 1 are equivalent. Also this is the default OID if none is given (which is only allowed if the OID parameter contains only a single row). This means that plt(...,'xy',[x y w h]) is equivalent to plt(...,'xy',[0 x y w h]).
-1 Represents the axis containing the traceIDs.
-2 Represents the axis containing the menu box items.
-3 This is similar to OID 0 except that in addition to adjusting the positions of the left & right axes, it also adjusts the associated cursor object positions and sizes (TraceID box, menubox, cursor readouts, etc.). For small axes, this can sometimes scale the cursor object too small or too close to the axis so there is a way to define this scaling independently as follows:
  AxisSize   = [.3 .3]; AxisPosition = [.2 .4];
  CursorSize = [.5 .5];
  plt(...,'xy',[-3 AxisPosition AxisSize + CursorSize*1i]);
The correction for the cursor size (using the imaginary component) may be applied in both x & y directions as in the above example, or it may be applied to either direction alone. Both the plt50.m and editz.m example programs demonstrate the use of the imaginary component in the y direction only.
other All graphical objects created by plt as well as those later created in the same figure window have a unique OID and therefore may be repositioned using the xy parameter. To determine an object's OID, enter the repositioning mode by right-clicking on the delta cursor button. Then clicking on any other object will display its OID followed by its current position coordinates.

For example:
plt(...,'xy',[-1 .01 .8 .12 .18; 1 .2 .16 .7 .8]);
 will set the traceID box to normalized position [.01 .8 .12 .18] and set the main axis to normalized position [.2 .16 .7 .8].

If you only want to specify the position of the main plot axis, the OID is optional. For example, the following two lines are equivalent:
plt(...,'xy',[1 .2 .16 .7 .8]);
plt(...,'xy',[  .2 .16 .7 .8]);

Although you can determine and enter these position coordinates manually, it is usually far easier to use the plt repositioning mode to determine the coordinates. See GUI building with plt to learn how this is done. That section also demonstrates in detail how to use the xy parameter to reposition any of the graphical objects in the plt figure window.

AxisPos

 plt(...,'AxisPos',p);
Usually, the size and position of the plot and TraceID box are modified using the xy parameter described above, however AxisPos provides an alternate method that is included primarily for backward compatibility with older programs written before the xy parameter was added. Although on rare occasions the AxisPos parameter may be easier to use than the xy parameter. p is a 4-element vector that modifies the size and position of the plot axis in the figure window. The first two elements modify the x and y coordinates of the lower left corner of the axis. The last two elements modify the axis width and height respectively. For example if p = [1 1 .9 1], the width of the plot will shrink by 10%. If  p = [1 2 1 .8] then the space between the bottom of the figure window and the bottom of the x-axis will double and the plot height will shrink by 20%. Changing the size and position of the axis is often useful when building applications to make room for additional GUI objects. If p is a 5-element vector, the width of the trace ID box is increased by a factor of p(5) to allow longer trace names. If p is an 8 element vector, the position of the trace ID box (xLeft,yBottom,width,height) is multiplied by the last four elements of p (i.e. p(5:8))

axisCB

 plt(...,'axisCB',s);
Evaluate string s when either the x or y-axis limits are changed. This callback function can also be specified by the cursor command cur(cid,'axisCB',fcn) which is described in more detail in the cursor commands section. At the top of that section, there is also a table that describes the string substitutions that plt performs on the string before evaluating it. These substitutions can make the callback more powerful while using less code. In addition to a string, s may also be a function handle of the form @func or {@func,arg1,arg2,...,argn}. Note that the string substitutions can't be used with the function handle form of this parameter.

Note that if the function is defined as a string argument often consecutive single quote characters are required (quotes within quotes). In that case readability can be improved by replacing all sequences of two consecutive single quotes with a double quote character. For example 'disp(''ABC'');' could be written as 'disp("ABC");'. Note that this trick also works for Matlab callbacks in general if you are using a relatively recent version of Matlab, but not for older versions. But it does work for any callback defined within a plt(...) function call regardless of the Matlab version.

moveCB

 plt(...,'moveCB',s);
Evaluate string s whenever the cursor is moved. This callback function can also be specified by the cursor command cur(cid,'moveCB',fcn) which is described in more detail in the cursor commands section. The moveCB is not really an axis property, but is included in this section because of the parallels with the above axisCB parameter. As with the axisCB parameter, the string substitutions are performed before evaluation. You may use function handle forms as well if you don't need the string substitutions.

ENApre

 plt(...,'ENApre',[ENAx ENAy]);
       ENAx or ENAy = 0 to disable metric prefixes on the x/y axis.
       ENAx or ENAy = 1 to enable metric prefixes on the x/y axis (default).
       If the argument has only one value, then it is used for both ENAx & ENAy.
When metric prefixes are enabled plt will choose the best unit for the respective axis. As an example, suppose the x-axis label is 'seconds' and the x-axis data is [0 1 2 3 4 5]*1e-8. With metric prefixes disabled, the x-axis tick-labels and cursor readout will be in scientific notation. With metric prefixes enabled, the x-axis label will change to "nano-seconds" and scientific notation will no longer be required, making the graph and cursors far more readable. (Note: metric prefixes are not used on the right-hand axis).

AxisLink

 plt(...,'AxisLink',m);
Tells plt to start with the left/right axes linked if m=1 or unlinked if m=0. For more details about linking the axes, see the right hand axis section.

+AxisProp
-AxisProp
<LabelProp
>LabelProp
.LabelProp
^TitleProp
"TtxtProp
?TboxProp

Property prefixes

  • If a property name is prefixed with a + or a - character then the property value will be applied to the left or right-hand axis respectively.
  • If a property name is prefixed with a <, >, . or a ^ character then the property value will be applied to the left hand axis label, right-hand axis label, x axis label, or the axis title respectively.
  • If a property name is prefixed with a " then the property value will be applied to the TraceID text.
  • If a property name is prefixed with a ? then the property value will be applied to the TraceID box (i.e. the axis containing the TraceID text).
Some examples:

plt(...,'+Ycolor',[0 0 1],'-Yscale','Log');
In this example, plt will assign the value [0 0 1] (blue) to the Ycolor property of the main (left-hand) axis, and it will apply the value 'Log' to the Yscale property of the right hand axis. The plus and minus signs are referred to as "property prefix characters" and in this case specifies which axis you want to modify.

plt(...,'>FontName','Lucida Handwriting');
In this example, the font used for the right-hand axis label is changed to Lucida Handwriting.

plt(...,'+<.^FontSize',13);
This example shows that more than one property prefix character may be included in front of a property name. In this case, the font size for the left-hand axis tick labels, the left y-label, the x-label, and the axis title are all increased to 13.

plt(x,[y1;y2;y3],'?pos',[.01 .4 .1 .4]);
plt(x,[y1;y2;y3],'xy',[-1 .01 .4 .1 .4]);
The above two lines are equivalent. They both move the location of the TraceID box from its default position to the normalized position [.01 .4 .1 .4]. The first line uses the property prefix for the TraceID box and the second line makes use of the 'xy' parameter.

The example programs hermite.m, pub0.m, and xChart.m also demonstrate the use of these property prefix characters.

Note that if a property name appears without one of these eight leading prefix characters (+-<>.^"?), then the property value will be assigned to all the lines that have been defined so far in the argument list. This is described more completely in the last entry of the Trace properties section.

SubPlot

 plt(...,'SubPlot',v);
Normally plt puts all the defined traces on a single plot (which may have left and right-hand y-axes) that fills most of the figure area. However, there are two methods (each with their unique advantages) to create more than one plot in a single figure. The first method is by using the 'Fig' parameter which is described at the end of the Labels and figure properties section. The second method is to use the SubPlot parameter which is described here.

When the SubPlot parameter is used, all the plots in the figure will be arranged in either one or multiple columns. All plots in a column usually use the same x-axis which allows all the cursors in the column to move left or right together. (This is called the "Linked" mode). With the alternate mode (called "Independent") however, each plot even within the same column may have different x-axis values. The subplot in the lower left corner has a special designation (the main plot) since that is the only plot that includes a traceID box. Also, some of the cursoring features are only available on the main plot (peak/valley finder, delta cursors, expansion history, the Mark/Zout/LinX/LinY tags, the x-axis slider, multi-cursors and the xView slider. (The 'Fig' parameter method doesn't suffer from any of these restrictions since each plot is a "main" plot, although linked cursors are not available with that method.) Each subplot however has its own y-axis cursor readout. These cursor readouts are easy to identify since their background color matches the trace and axis colors. The full panning and zooming features of plt are supported for each subplot. When the x-axis of any subplot is modified (by panning or zooming for instance), the x-axis limits of all the other subplots in the same column are set to match the newly selected range.

Single column
 To create a single column of plots (all using the same x axis), the subplot parameter should consist of n positive numbers, where n is the number of plots desired. Each number specifies the percent of the area to be occupied by each plot (starting from the bottom). Normally the sum of the array should be 100, although if the sum is less than 100, there will be some unused space at the top of the figure. For example, 'SubPlot',[40 30 15 15] tells plt to create four plots. The bottom one (the "main" plot) will use 40% of the available height. The plot above that will use 30% of the height, and the remaining two will take 15% each. Each subplot except the main (lower) plot is normally assigned a single trace, with the last trace defined appearing in the uppermost axis, the second to last trace appearing in the axis below that, etc. For example, the command plt(1:50,rand(7,50),'SubPlot',[40 30 15 15]) will create seven traces containing random data, with the first four traces displayed on the main (lower) plot (with a traceID box containing four labels), and the last three traces are displayed in the other three subplots. The example script demo\subplt.m demonstrates the use of single column subplots. Usually, only the main plot may contain multiple traces, although the SubTrace parameter (see below) allows you to change this behavior.

Dual column
 The example script demo\subplt8.m demonstrates the use of dual-column subplots. To create two columns of plots, insert a negative number into the subplot argument. The number of entries to the left of the negative number indicates how many plots will appear in the left column, and similarly, the number of entries to the right of the negative number indicates the number of plots in the right column. The negative number itself specifies the width (in percent) of the left column. Some examples will help clarify this. In all the examples below, assume that y = [a b c d e f] where a through f are column vectors of the same length as x.

plt(x,y,'SubPlot',[100 -60 100],'Right',[2 3]);
The subplot parameter tells plt to create two plots both of which fill the entire height available in the plotting area of the figure. The left (main) plot fills 60% of the width with the second plot filling the remaining 40%. Since six traces are defined, the first five traces (a through e) appear on the main plot and the last trace (f) appears on the right plot. Since the TraceID parameter was not included, the TraceID box next to the main plot will contain the default trace labels (Line1 thru Line5). To label the traces more informatively, a parameter such as 'TRACEid',{'a' 'b' 'c' 'd' 'e'} could be added to the plt argument list. Since the 'Right' parameter was included, the main plot will include both right and left axes, with the 2nd and 3rd traces (b and c) on the right and the remaining three traces (a, d,e) on the left. The left and right axes will be separated by enough space to leave room for the axis labels, and this space will be increased when the 'Right' parameter is used so that there is room for an axis label on the right side of the main (i.e. left) axis.

plt(x,y,'SubPlot',[50 30 20 -55 70 20]);
In this example, three plots will be created in the left column which fills 55% of the width of the plotting area. The main plot on the bottom (containing traces a & b) fills 50% of the height, the middle plot (trace c) fills 30%, and the top plot (trace d) fills the remaining 20% of the height. Two plots are created in the right column which fills the remaining 45% of the width. The lower of these (trace e) fills 70% of the height and the upper (trace f) fills 20%, with the upper 10% remaining blank. Note that both traces in the main plot use the left-hand axis since no 'Right' parameter was given and no limits or labels were specified for the right-hand axis. (With this many subplots it's best not to use a right-hand axis since it makes all the subplots significantly narrower to make room for the right-hand axis ticks and labels.)

plt(x,y,'LabelX',{'meters' 'pascals'},'Ylim'{[0 5] [0 .1]});
Even though the subplot argument is not included here, plt will split the plot horizontally as if you had included 'SubPlot',[100 50 100] in the argument list. This is because two different x-axis labels are specified with the 'LabelX' parameter and so plt recognizes that a second column is needed. The right column plot will contain trace f and the left column (main) plot will contain traces a thru e. Since two y-axis limits are specified, plt will put both left and right axes on the main plot. In this example the 'Right' parameter is not included, plt will default to putting the last trace of the main plot (trace e) on the right axis with the other four traces on the left axis. (Be careful not to confuse the concepts of the right and left axes of the main plot, with the right and left columns of subplots.) Also, remember that the 'Ylim' parameter can't specify axis limits for a subplot. To set the y-axis limits for the subplots, use the set command with the axis handles obtained from getappdata(gcf,'axis') or use the cur(cid,'xylim',p) command described here.

More than two columns
 As you can see from the example script demo\subplt16.m you may use as many columns as you want. The negative numbers in the subplot parameter are used to separate the plots into columns. For example 'SubPlot',[50 50 -30 50 50 -30 50 50 -30] specifies an array of six plots (2 rows and 3 columns). Each column is split 50/50 between the two plots. Since each of the 3 columns occupies 30% of the available plot width about 10% of the available width to the right of the last column will be blank (possibly to be filled in later with other graphic elements or controls). The width of the last column does not need to be specified. In this example, if the last number (-30) was omitted, the last column would take 40% of the available width since plt wants to fill the whole plot area unless instructed otherwise.

Plot spacing
 By default, plt allows plenty of space between the subplots to allow for axis ticks and labels. Sometimes you may want to decrease the horizontal or vertical spacing so that you can fit more plots into a given space or to allow each plot to have as much area as possible. Or you may want to increase the spacing to allow room to add additional controls or graphic elements. It would be awkward to require an additional array the size of SubPlot to specify the desired row and column spacing, so this information is embedded into the SubPlot argument. This is done by using the integer part to specify the plot heights and widths (as described above) and by using the fractional part to specify the deviations from the default inter-plot spacing. Fractional parts from 0 to .5 indicate the default spacing should be increased. Fractional parts from .5 to .9999 indicate the default spacing should be decreased. This is best shown by example. Consider a slight change from the previous example: 'SubPlot',[50.02 50.97 -30.96 50 50 -30.01 50 50] The first two fractional parts (.02 and .97) tell plt to increase spacing below the first plot by 2% and to decrease the spacing below the second plot by 3% (of the available plot height). The fractional parts of the two negative numbers (.96 and .01) tells plt to decrease the spacing to the left of the first column by 4% and to increase the spacing to the left of the second column by 1% (of the available plot width). At first, this may seem confusing, but with a little practice you will find that the SubPlot parameter gives you complete subplot positioning flexibility. In the rare situations where you can't get the subplots positioned as desired, you can always use the 'xy' parameter to move or resize any or all of the subplots.

Linked vs. Independent mode
 The three sample scripts mentioned so far use the default "linked" mode which is intended to be used when all the plots in each column have the same number of elements and the same x-axis limits. When you move a cursor, all the cursors for the remaining subplots in the same column will be moved left or right so all the cursors in the column remain vertically aligned. Likewise, if you change the x-axis limits of any plot (by panning or zooming) then the x-axis limits of the remaining plots in that column will also change so that all the plots in the column share the same x-axis limits. Note that changes in one column will never affect any of the other columns. When you don't want the cursors and x-axis limits to be linked in this manner, you should specify the "Independent mode" which is done by putting an "i" after the first SubPlot element. The sample script demo\subplt20.m and the application sig\pltZoom.m both demonstrate the use of the independent mode.

SubTrace

 When using subplots, it is important to understand that the default behavior is to allow only a single trace on each subplot except for the main axis (lower left). The main reason for this is to allow plt to provide a simple cursoring mechanism that allows every trace to be cursored. However, there are two situations where you may want to change this default behavior. The first is where cursoring is disabled (usually because the plot is to be used for publication instead of for data exploration). Since cursoring is not an issue, there is no reason to stick with the default behavior for assigning the traces to the axes. The second plot in the script demo\pub0.m  is an example of how the SubTrace parameter might by used in this situation. The second situation where you might want to use this parameter is when you plan on modifying the cursor behavior to make sense for the particular trace arrangement you have in mind. This requires a detailed understanding of plt's cursoring commands but is doable when the trace configuration and desired cursoring scheme are reasonably simple. An example of this second situation can be found in the script demo\weight.m.

There are two ways to use this parameter to assign the traces to the various subplots. For either method you must know how plt numbers the axes. Axis number one is always the main axis (lower left). Then axis two is the one directly above the main axis and axis three is the one above that, continuing to the top of the left column. Then the lowest axis of the second column (if it exists) is assigned to the next number, and continuing upwards as before. Finally after all the subplots have been assigned a number in this manner, the right-hand axis of the main plot (if it exists) is assigned to the next higher integer.

Suppose for example, you have 4 axes and 9 traces and that you want to put two traces on each of the first 3 axes and then put the remaining 3 traces on the last axis. The first way to do this is to specify how many traces to put on each axis, i.e. 'SubTrace',[2 2 2 3]. Instead of specifying how many traces are on each axis, an alternate way to do this is to specify which axis each trace goes on. So an equivalent to the previous parameter you could use 'SubTrace',[1 1 2 2 3 3 4 4 4]. Of course, this second method is always going to be longer than the first method, so you would likely only use it if you needed to assign the traces to the axes in a different order, for example 'SubTrace',[1 2 3 1 2 3 4 4 4] (which is not possible to specify using the first method). plt will always be able to figure out with method you are using.